001    /*
002     * Copyright 2004 Niclas Hedhman
003     * Copyright 2004-2005 Stephen McConnell
004     *
005     * Licensed  under the  Apache License,  Version 2.0  (the "License");
006     * you may not use  this file  except in  compliance with the License.
007     * You may obtain a copy of the License at
008     *
009     *   http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed  under the  License is distributed on an "AS IS" BASIS,
013     * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
014     * implied.
015     *
016     * See the License for the specific language governing permissions and
017     * limitations under the License.
018     */
019    
020    package net.dpml.tools.tasks;
021    
022    import java.io.File;
023    import java.io.FileFilter;
024    import java.io.FileInputStream;
025    import java.io.IOException;
026    import java.text.SimpleDateFormat;
027    import java.util.Calendar;
028    import java.util.Hashtable;
029    import java.util.Iterator;
030    import java.util.Map;
031    import java.util.Date;
032    import java.util.regex.Matcher;
033    import java.util.regex.Pattern;
034    
035    import javax.xml.transform.Transformer;
036    import javax.xml.transform.TransformerFactory;
037    import javax.xml.transform.stream.StreamResult;
038    import javax.xml.transform.stream.StreamSource;
039    
040    import net.dpml.transit.Transit;
041    
042    import org.apache.tools.ant.BuildException;
043    import org.apache.tools.ant.Project;
044    import org.apache.tools.ant.taskdefs.Copy;
045    import org.apache.tools.ant.types.FileSet;
046    
047    /**
048     * Site generation.
049     *
050     * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
051     * @version 1.1.0
052     */
053    public class DocTask extends GenericTask
054    {
055        private static final String ORG_NAME_VALUE = "The Digital Product Meta Library";
056        private static final String DOC_TEMP_VALUE = "docs";
057        private static final String DOC_SRC_VALUE = "docs";
058        private static final String DOC_RESOURCES_VALUE = "resources";
059        private static final String DOC_THEME_VALUE = "formal";
060        private static final String DOC_FORMAT_VALUE = "html";
061        private static final String DOC_DATE_FORMAT_VALUE = "yyyy-MMM-dd";
062        private static final String DOC_STYLE_VALUE = "standard";
063        private static final String DOC_ENTRY_VALUE = "";
064        private static final String DOC_LOGO_RIGHT_FILE_VALUE = "";
065        private static final String DOC_LOGO_RIGHT_URL_VALUE = "";
066        private static final String DOC_LOGO_LEFT_FILE_VALUE = "";
067        private static final String DOC_LOGO_LEFT_URL_VALUE = "";
068        private static final String DOC_LOGO_MIDDLE_FILE_VALUE = "";
069        private static final String DOC_LOGO_MIDDLE_URL_VALUE = "";
070        private static final String DOC_BRAND_NAME_VALUE = "DPML";
071        private static final String DOC_HOME_PATH_VALUE = "index.html";
072    
073       /**
074        * Constant organization key.
075        */
076        public static final String ORG_NAME_KEY = "project.organization.name";
077    
078       /**
079        * Constant temp docs key.
080        */
081        public static final String DOC_TEMP_KEY = "project.target.temp.docs";
082    
083       /**
084        * Constant docs src key.
085        */
086        public static final String DOC_SRC_KEY = "project.docs.src";
087    
088       /**
089        * Constant docs resources key.
090        */
091        public static final String DOC_RESOURCES_KEY = "project.docs.resources";
092    
093       /**
094        * Constant docs theme key.
095        */
096        public static final String DOC_THEME_KEY = "project.docs.theme";
097    
098       /**
099        * Constant docs output format key.
100        */
101        public static final String DOC_FORMAT_KEY = "project.docs.output.format";
102    
103       /**
104        * Constant docs date format key.
105        */
106        public static final String DOC_DATE_FORMAT_KEY = "project.docs.date.format";
107    
108       /**
109        * Constant docs output style key.
110        */
111        public static final String DOC_STYLE_KEY = "project.docs.output.style";
112    
113       /**
114        * Constant docs entry-point key.
115        */
116        public static final String DOC_ENTRY_KEY = "project.docs.entry-point";
117    
118       /**
119        * Constant docs logo-right-file key.
120        */
121        public static final String DOC_LOGO_RIGHT_FILE_KEY = "project.docs.logo.right.file";
122    
123       /**
124        * Constant docs logo-right url key.
125        */
126        public static final String DOC_LOGO_RIGHT_URL_KEY = "project.docs.logo.right.url";
127    
128       /**
129        * Constant docs logo-left file key.
130        */
131        public static final String DOC_LOGO_LEFT_FILE_KEY = "project.docs.logo.left.file";
132    
133       /**
134        * Constant docs logo-left url key.
135        */
136        public static final String DOC_LOGO_LEFT_URL_KEY = "project.docs.logo.left.url";
137    
138       /**
139        * Constant docs logo-middle file key.
140        */
141        public static final String DOC_LOGO_MIDDLE_FILE_KEY = "project.docs.logo.middle.file";
142    
143       /**
144        * Constant docs logo-middle url key.
145        */
146        public static final String DOC_LOGO_MIDDLE_URL_KEY = "project.docs.logo.middle.url";
147    
148       /**
149        * Constant docs brand key.
150        */
151        public static final String DOC_BRAND_NAME_KEY = "project.docs.brand.name";
152    
153       /**
154        * Constant docs anchor url key.
155        */
156        public static final String DOC_ANCHOR_URL_KEY = "project.docs.anchor.url";
157    
158       /**
159        * Constant docs home page path.
160        */
161        public static final String DOC_HOME_PATH_KEY = "project.docs.home.path";
162    
163        private String m_theme;
164        private File m_baseToDir;
165        private File m_baseSrcDir;
166        private File m_dest;
167    
168       /**
169        * Return the assigned theme.
170        * @return the theme
171        */
172        public String getTheme()
173        {
174            if( m_theme != null )
175            {
176                return m_theme;
177            }
178            String theme = getProject().getProperty( DOC_THEME_KEY );
179            if( null != theme )
180            {
181                return theme;
182            }
183            else
184            {
185                return getResource().getProperty( DOC_THEME_KEY, "formal" );
186            }
187        }
188        
189       /**
190        * Set a directory for ultimate replication of the generated documentation.
191        * @param dir the utilimate destination directory
192        */
193        public void setDest( File dir )
194        {
195            m_dest = dir;
196        }
197    
198       /**
199        * Set the doc theme.
200        * @param theme the theme name
201        */
202        public void setTheme( final String theme )
203        {
204            m_theme = theme;
205        }
206    
207       /**
208        * Initialize the task.
209        * @exception BuildException if a build error occurs
210        */
211        public void init() throws BuildException
212        {
213            if( !isInitialized() )
214            {
215                super.init();
216                final Project project = getProject();
217                project.setNewProperty( ORG_NAME_KEY, ORG_NAME_VALUE );
218                project.setNewProperty( DOC_SRC_KEY, DOC_SRC_VALUE );
219                project.setNewProperty( DOC_RESOURCES_KEY, DOC_RESOURCES_VALUE );
220                project.setNewProperty( DOC_FORMAT_KEY, DOC_FORMAT_VALUE );
221                project.setNewProperty( DOC_DATE_FORMAT_KEY, DOC_DATE_FORMAT_VALUE );
222                project.setNewProperty( DOC_STYLE_KEY, DOC_STYLE_VALUE );
223                project.setNewProperty( DOC_ENTRY_KEY, DOC_ENTRY_VALUE );
224                project.setNewProperty( DOC_TEMP_KEY, DOC_TEMP_VALUE );
225                project.setNewProperty( DOC_LOGO_RIGHT_FILE_KEY, DOC_LOGO_RIGHT_FILE_VALUE );
226                project.setNewProperty( DOC_LOGO_RIGHT_URL_KEY, DOC_LOGO_RIGHT_URL_VALUE );
227                project.setNewProperty( DOC_LOGO_LEFT_FILE_KEY, DOC_LOGO_LEFT_FILE_VALUE );
228                project.setNewProperty( DOC_LOGO_LEFT_URL_KEY, DOC_LOGO_LEFT_URL_VALUE );
229                project.setNewProperty( DOC_LOGO_MIDDLE_FILE_KEY, DOC_LOGO_MIDDLE_FILE_VALUE );
230                project.setNewProperty( DOC_LOGO_MIDDLE_URL_KEY, DOC_LOGO_MIDDLE_URL_VALUE );
231                project.setNewProperty( DOC_BRAND_NAME_KEY, DOC_BRAND_NAME_VALUE );
232            }
233        }
234    
235       /**
236        * Execute the task.
237        */
238        public void execute()
239        {
240            final Project project = getProject();
241            final File srcDir = getContext().getTargetBuildDocsDirectory();
242            if( !srcDir.exists() )
243            {
244                return;
245            }
246            log( "Filtered source: " + srcDir.getAbsolutePath() );
247    
248            //
249            // create the temporary directory into which we generate the
250            // navigation structure (normally target/temp/docs)
251            //
252    
253            final File temp = getContext().getTargetTempDirectory();
254            final File destDir = new File( temp, "docs" );
255            mkDir( destDir );
256    
257            //
258            // get the theme, output formats, etc.
259            //
260    
261            final File docs = getContext().getTargetDocsDirectory();
262            log( "Destination: " + docs.getAbsolutePath() );
263            mkDir( docs );
264            final String theme = getTheme();
265            final String output = getOutputFormat();
266            final String home = getHomePath();
267            final File themeRoot = getThemesDirectory();
268            final File themeDir = new File( themeRoot, theme + "/" + output );
269            
270            final File target = getContext().getTargetDirectory();
271            final String resourcesPath = project.getProperty( DOC_RESOURCES_KEY );
272            final File resources = new File( target, resourcesPath );
273    
274            log( "Year: " + getYear() );
275            log( "Theme: " + themeDir );
276    
277            //
278            // initiate the transformation starting with the generation of
279            // the navigation structure based on the src directory content
280            // into the temporary destingation directory, copy the content
281            // sources to to the temp directory, transform the content and
282            // generated navigation in the temp dir using the selected them
283            // into the final docs directory, and copy over resources to
284            // the final docs directory
285            //
286    
287            try
288            {
289                transformNavigation( themeDir, srcDir, destDir );
290                copySources( srcDir, destDir );
291                transformDocs( themeDir, destDir, docs );
292                copyThemeResources( themeDir, docs );
293                copySrcResources( resources, docs );
294            }
295            catch( BuildException e )
296            {
297                throw e;
298            }
299            catch( Throwable e )
300            {
301                log( "XSLT execution failed: " + e.getMessage() );
302                throw new BuildException( e );
303            }
304            
305            if( null != m_dest )
306            {
307                copy( docs, m_dest, "**/*", "" );
308            }
309        }
310        
311        private File getThemesDirectory()
312        {
313            return new File( Transit.DPML_PREFS, "dpml/tools/themes" );
314        }
315    
316        private String getHomePath()
317        {
318            return getProject().getProperty( DOC_HOME_PATH_KEY );
319        }
320    
321        private String getOutputFormat()
322        {
323            return getProject().getProperty( DOC_FORMAT_KEY );
324        }
325    
326        private String getOutputStyle()
327        {
328            return getProject().getProperty( DOC_STYLE_KEY );
329        }
330    
331        private String getDateFormat()
332        {
333            return getProject().getProperty( DOC_DATE_FORMAT_KEY );
334        }
335    
336        private void transformNavigation( final File themeDir, final File source, final File dest )
337        {
338            final File xslFile = new File( themeDir,  "nav-aggregate.xsl" );
339            if( !xslFile.exists() )
340            {
341                return;  // Theme may not use navigation.
342            }
343            log( "Transforming navigation." );
344            try
345            {
346                transformTrax(
347                    source, dest, xslFile,
348                    "^.*/navigation.xml$", "", ".xml" );
349            }
350            catch( BuildException e )
351            {
352                throw e;
353            }
354            catch( Throwable e )
355            {
356                final String error = 
357                  "Transformation failure: " + source;
358                throw new BuildException( error, e );
359            }
360        }
361    
362        private void copySources( final File source, final File dest )
363        {
364            copy( source, dest, "**/*", "**/navigation.xml" );
365        }
366    
367        private void transformDocs( final File themeDir, final File build, final File docs )
368        {
369            String style = getOutputStyle();
370            File xslFile = new File( themeDir,  style + ".xsl" );
371            String output = getOutputFormat();
372            log( "Transforming content." );
373            transformTrax(
374              build, docs, xslFile,
375              "^.*\\.xml$", "^.*/navigation.xml$", "." + output );
376        }
377    
378        private void copySrcResources( final File resources, final File docs )
379        {
380            copy( resources, docs, "**/*", "" );
381        }
382    
383        private void copyThemeResources( final File themeDir, final File docs )
384        {
385            final File fromDir = new File( themeDir, "resources" );
386            copy( fromDir, docs, "**/*", "" );
387        }
388    
389        private void copy( final File fromDir, final File toDir, final String includes, final String excludes )
390        {
391            if( !fromDir.exists() )
392            {
393                return;
394            }
395    
396            final FileSet from = new FileSet();
397            from.setDir( fromDir );
398            from.setIncludes( includes );
399            from.setExcludes( excludes );
400    
401            mkDir( toDir );
402    
403            final Copy copy = (Copy) getProject().createTask( "copy" );
404            copy.setTodir( toDir );
405            copy.addFileset( from );
406            copy.setPreserveLastModified( true );
407            copy.execute();
408        }
409    
410    
411        private void transformTrax(
412                final File srcDir, final File toDir, final File xslFile,
413                final String includes, final String excludes, final String extension )
414            throws BuildException
415        {
416            FileInputStream fis = null;
417            try
418            {
419                ClassLoader cl = getClass().getClassLoader();
420                Thread.currentThread().setContextClassLoader( cl );
421                StreamSource source = new StreamSource( xslFile );
422                final TransformerFactory tfactory = TransformerFactory.newInstance();
423                final Transformer transformer = tfactory.newTransformer( source );
424                final RegexpFilter filter = new RegexpFilter( includes, excludes );
425    
426                m_baseToDir = toDir;
427                m_baseSrcDir = srcDir.getAbsoluteFile();
428                String entrypoint = getEntryPoint();
429                if( "".equals( entrypoint ) )
430                {
431                    transform( transformer, m_baseSrcDir, toDir, filter, extension );
432                }
433                else
434                {
435                    File fileToConvert = new File( m_baseSrcDir, entrypoint );
436                    transformFile(
437                      transformer, fileToConvert, m_baseSrcDir, entrypoint, extension, m_baseToDir );
438                }
439            }
440            catch( BuildException e )
441            {
442                throw e;
443            }
444            catch( Exception e )
445            {
446                throw new BuildException( e.getMessage(), e );
447            }
448            finally
449            {
450                if( fis != null )
451                {
452                    try
453                    {
454                        fis.close();
455                    } 
456                    catch( IOException f )
457                    {
458                        log( f.toString() );
459                    }
460                }
461            }
462        }
463    
464        private void transform( final Transformer transformer, final File srcDir, final File toDir,
465            final FileFilter filter, final String extension )
466            throws BuildException
467        {
468            boolean recursive = isRecursive();
469            final File[] content = srcDir.listFiles( filter );
470            for( int i=0; i < content.length; i++ )
471            {
472                String base = content[i].getName();
473                if( content[i].isDirectory() && recursive )
474                {
475                    final File newDest = new File( toDir, base );
476                    newDest.mkdirs();
477                    transform( transformer, content[i], newDest, filter, extension );
478                }
479                if( content[i].isFile() )
480                {
481                    transformFile( transformer, content[i], srcDir, base, extension, toDir );
482                }
483            }
484        }
485    
486        private void transformFile( Transformer transformer, File content, File srcDir,
487                                    String base, String extension, File toDir )
488        {
489            String userDir = System.getProperty( "user.dir" );
490            System.setProperty( "user.dir", toDir.getAbsolutePath() );
491            final String year = getYear();
492            final String org = getOrganization();
493            final String copyright =
494              "Copyright " 
495              + year 
496              + ", " 
497              + org 
498              + " All rights reserved.";
499    
500            final String svnRoot = getProject().getProperty( DOC_ANCHOR_URL_KEY );
501            final String svnSource = svnRoot + getRelSrcPath( srcDir ) + "/" + base;
502    
503            final int pos = base.lastIndexOf( '.' );
504            if( pos > 0 )
505            {
506                base = base.substring( 0, pos );
507            }
508            base = base + extension;
509    
510            final File newDest = new File( toDir, base );
511            final StreamSource xml = new StreamSource( content );
512            final StreamResult out = new StreamResult( newDest );
513    
514            transformer.clearParameters();
515            transformer.setParameter( "directory", getRelToPath( toDir ) );
516            transformer.setParameter( "fullpath", getRelToPath( newDest ) );
517            transformer.setParameter( "file", base );
518            transformer.setParameter( "svn-location", svnSource );
519            transformer.setParameter( "copyright", copyright );
520            transformer.setParameter(
521                "logoright_file",
522                getProject().getProperty( DOC_LOGO_RIGHT_FILE_KEY ).trim() );
523            transformer.setParameter(
524                "logoright_url",
525                getProject().getProperty( DOC_LOGO_RIGHT_URL_KEY ).trim() );
526            transformer.setParameter(
527                "logoleft_file",
528                getProject().getProperty( DOC_LOGO_LEFT_FILE_KEY ).trim() );
529            transformer.setParameter(
530                "logoleft_url",
531                getProject().getProperty( DOC_LOGO_LEFT_URL_KEY ).trim() );
532            transformer.setParameter(
533                "logomiddle_file",
534                getProject().getProperty( DOC_LOGO_MIDDLE_FILE_KEY ).trim() );
535            transformer.setParameter(
536                "logomiddle_url",
537                getProject().getProperty( DOC_LOGO_MIDDLE_URL_KEY ).trim() );
538            transformer.setParameter(
539                "brand_name",
540                getProject().getProperty( DOC_BRAND_NAME_KEY ).trim() );
541            transformer.setParameter( "generated_date", getNow() );
542            setOtherProperties( transformer );
543            try
544            {
545                transformer.transform( xml, out );
546            }
547            catch( BuildException e )
548            {
549                throw e;
550            }
551            catch( Throwable e )
552            {
553                final String error = 
554                  "An error occured while attempting to transform document: "
555                  + getRelToPath( newDest );
556                throw new BuildException( error, e, getLocation() );
557            }
558            finally
559            {
560                System.setProperty( "user.dir", userDir );
561            }
562        }
563    
564        private String getRelToPath( final File dir )
565        {
566            final String basedir = m_baseToDir.getAbsolutePath();
567            final String curdir = dir.getAbsolutePath();
568            return curdir.substring( basedir.length() );
569        }
570    
571        private String getRelSrcPath( final File dir )
572        {
573            final String basedir = m_baseSrcDir.getAbsolutePath();
574            final String curdir = dir.getAbsolutePath();
575            return curdir.substring( basedir.length() );
576        }
577    
578       /**
579        * Utility regualar expression filter.
580        */
581        public class RegexpFilter implements FileFilter
582        {
583            private Pattern m_includes;
584            private Pattern m_excludes;
585    
586           /**
587            * New filter creation.
588            * @param includes the includes
589            * @param excludes the excludes
590            */
591            public RegexpFilter( final String includes, final String excludes )
592            {
593                m_includes = Pattern.compile( includes );
594                m_excludes = Pattern.compile( excludes );
595            }
596    
597           /**
598            * Test supplied file for acceptance.
599            * @param file the candidate
600            * @return TRUE if acceptable
601            */
602            public boolean accept( final File file )
603            {
604                final String basename = file.getName();
605    
606                if( basename.equals( ".svn" ) )
607                {
608                    return false;
609                }
610    
611                if( basename.equals( "CVS" ) )
612                {
613                    return false;
614                }
615    
616                if( file.isDirectory() )
617                {
618                    return true;
619                }
620    
621                final String fullpath = file.getAbsolutePath().replace( '\\', '/' );
622    
623                Matcher m = m_includes.matcher( fullpath );
624                if( !m.matches() )
625                {
626                    return false;
627                }
628    
629                m = m_excludes.matcher( fullpath );
630                return !m.matches();
631            }
632        }
633    
634        private String getYear()
635        {
636            String year = getProject().getProperty( "magic.year" );
637            if( year != null )
638            {
639                return year;
640            }
641            else
642            {
643                Calendar cal = Calendar.getInstance();
644                return Integer.toString( cal.get( Calendar.YEAR ) );
645            }
646        }
647    
648        private String getOrganization()
649        {
650            return getProject().getProperty( ORG_NAME_KEY );
651        }
652    
653        private boolean isRecursive()
654        {
655            return "".equals( getEntryPoint() );
656        }
657    
658        private String getEntryPoint()
659        {
660            String point = getProject().getProperty( DOC_ENTRY_KEY );
661            if( point == null )
662            {
663                return "";
664            }
665            return point;
666        }
667    
668        private void setOtherProperties( Transformer transformer )
669        {
670            String prefix = "project.docs.xsl.";
671            int prefixLen = prefix.length();
672    
673            Hashtable p = getProject().getProperties();
674            Iterator list = p.entrySet().iterator();
675            while( list.hasNext() )
676            {
677                Map.Entry entry = (Map.Entry) list.next();
678                String key = (String) entry.getKey();
679                if( key.startsWith( prefix ) )
680                {
681                    String value = (String) entry.getValue();
682                    key = key.substring( prefixLen );
683                    transformer.setParameter( key, value );
684                    log( "Setting " + key + "=" + value );
685                }
686            }
687        }
688    
689        private String getNow()
690        {
691            Date now = new Date();
692            SimpleDateFormat sdf = new SimpleDateFormat( getDateFormat() );
693            String result = sdf.format( now );
694            return result;
695        }
696    }